[material_ui, cupertino_ui] Fix API doc references by Piinks · Pull Request #12274 · flutter/packages

Piinks · 2026-07-22T21:49:56Z

Fix doc references in material_ui and cupertino_ui
Towards flutter/flutter#189629

I also commented out youtube directives since they do not work outside of the SDK.

There are some references we cannot fix in the design packages themselves, largely due tot he fact that material_ui and cupertino_ui export the widgets library. That pulls in doc references from the widgets library that cannot be resolved outside of the scope of the SDK.

We can change the doc upstream in the SDK, but that feel like a poor choice to make the docs less helpful in the SDK in order to resolve a reference issue in a downstream package.
Something we are planning for after the initial 1.0 is to remove the export of widgets from both packages, which will resolve the remaining issues.

Pre-Review Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

flutter-dashboard · 2026-07-22T21:50:06Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

gemini-code-assist

Code Review

This pull request replaces documentation macros with inline documentation for scrollbars and primary scroll views, adds @docImport statements, and comments out {@youtube} directives. Feedback from the reviewer indicates that using // instead of /// to comment out the youtube directives breaks Dart's documentation comment blocks, detaching preceding documentation from their declarations. The reviewer suggests using /// and removing the @ symbol to keep the comment blocks contiguous.

dkwingsmt · 2026-07-22T21:55:29Z

+/// visible.
 ///
-/// {@macro flutter.widgets.Scrollbar}
+/// By default, the thumb will fade in and out as the child scroll view


This change and alike duplicate with #12271 . While I'm leaning towards my approach, I'm ok with either, and let me know what you think.

Gotcha gotcha, sorry I missed that. It has given me a new idea for the youtube ones too. I prefer your solution, I will revert those duped instances here.

Piinks · 2026-07-22T23:03:14Z

/gemini review

gemini-code-assist

Code Review

This pull request replaces the {@youtube} directive with standard text links to the Flutter YouTube channel across various Cupertino and Material widgets, and adds @docImport directives to several library files. Feedback on the changes identifies typos using four slashes (////) instead of three (///) for documentation comments in scrollbar.dart and reorderable_list.dart. Additionally, incorrect widget references were noted in the documentation comments for sheet.dart and scaffold.dart.

dkwingsmt

LGTM. Great solution!

auto-submit · 2026-07-23T00:06:05Z

autosubmit label was removed for flutter/packages/12274, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

Piinks · 2026-07-23T00:10:51Z

Oo interesting scenario here. We enabled batch release for these packages, and removed the publish_to: none, but now we're failing repo checks for not bumping the version. @justinmc do you know the right steps to land things now?

chunhtai · 2026-07-27T09:27:54Z

the repo check is failing because it expects a change log entry in https://github.com/flutter/packages/tree/main/packages/cupertino_ui/pending_changelogs

just copy the template file and fill in the detail, same for material_ui package.

For example this one in go_router https://github.com/flutter/packages/blob/main/packages/go_router/pending_changelogs/change_2026_06_07_1780787180781.yaml

Piinks · 2026-07-27T19:30:16Z

Gotcha, thanks @chunhtai! Can you document the process and check it in to the repo for reference?

chunhtai · 2026-07-27T22:41:31Z

the process is documented in https://github.com/flutter/flutter/tree/master/docs/ecosystem/release#batch-release

The error message in repo_check seems to be a bit confusing, let me update that

Piinks · 2026-07-28T16:15:53Z

Gotcha, thanks!

justinmc

LGTM 👍

justinmc · 2026-07-28T16:46:06Z

 /// An iOS-style activity indicator that spins clockwise.
 ///
-/// {@youtube 560 315 https://www.youtube.com/watch?v=AENVH-ZqKDQ}
+/// Learn more about [CupertinoActivityIndicator] on the [Flutter YouTube channel](https://www.youtube.com/watch?v=AENVH-ZqKDQ).


Is this something that will be replaced with an embedded video in the future when it's supported? I guess we can find these by searching for the youtube URL in the codebase.

Yup! Filed dart-lang/pub-dev#9490 to see if @youtube can be supported

justinmc · 2026-07-28T16:46:47Z

I'm making a note to check in next Monday and see if this gets released as expected!

justinmc · 2026-07-28T16:47:42Z

  /// the [NavigationDestination] is focused, hovered, or pressed.
  final WidgetStateProperty<Color?>? overlayColor;

-  //// The text style of the label.


auto-submit · 2026-07-28T17:08:56Z

autosubmit label was removed for flutter/packages/12274, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

Piinks requested review from dkwingsmt and justinmc July 22, 2026 21:49

flutter-dashboard Bot added the CICD Run CI/CD label Jul 22, 2026

gemini-code-assist Bot reviewed Jul 22, 2026

View reviewed changes

Comment thread packages/cupertino_ui/lib/cupertino_ui.dart Outdated

Comment thread packages/material_ui/lib/material_ui.dart Outdated

Piinks added p: cupertino_ui p: material_ui labels Jul 22, 2026

dkwingsmt reviewed Jul 22, 2026

View reviewed changes

Comment thread packages/cupertino_ui/lib/src/activity_indicator.dart Outdated

dkwingsmt reviewed Jul 22, 2026

View reviewed changes

github-actions Bot added the triage-framework Should be looked at in framework triage label Jul 22, 2026

gemini-code-assist Bot reviewed Jul 22, 2026

View reviewed changes

dkwingsmt approved these changes Jul 22, 2026

View reviewed changes

Piinks added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 22, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 23, 2026

Piinks added 4 commits July 28, 2026 11:09

Fix API doc references

1f89883

Updates

4e48ae1

G review

ce34a47

Add pending changelogs

2142df6

Piinks force-pushed the docRefs branch from 0096807 to 2142df6 Compare July 28, 2026 16:13

Piinks added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

Piinks mentioned this pull request Jul 28, 2026

[material_ui, cupertino_ui] Migrate macros that contain @tool #12271

Merged

11 tasks

justinmc approved these changes Jul 28, 2026

View reviewed changes

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

Piinks added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

auto-submit Bot merged commit e6b99e0 into flutter:main Jul 28, 2026
13 checks passed

engine-flutter-autoroll mentioned this pull request Jul 29, 2026

Roll Packages from 3e636359fb00 to dd11626c81a3 (11 revisions) flutter/flutter#190216

Open

Uh oh!

Conversation

Piinks commented Jul 22, 2026

Pre-Review Checklist

Footnotes

Uh oh!

flutter-dashboard Bot commented Jul 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dkwingsmt Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Piinks Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Piinks commented Jul 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Jul 23, 2026

Uh oh!

Piinks commented Jul 23, 2026

Uh oh!

chunhtai commented Jul 27, 2026

Uh oh!

Piinks commented Jul 27, 2026

Uh oh!

chunhtai commented Jul 27, 2026

Uh oh!

Piinks commented Jul 28, 2026

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

justinmc Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Piinks Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

justinmc Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

justinmc Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Jul 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dkwingsmt Jul 22, 2026 •

edited

Loading